# Требования к внесению изменений в код

Перед выполнением большинства команд git желательно актуализировать локальное состояние
с облаком, чтобы потом не возникали конфликты слияния:

```bash
git pull --rebase
```

## 1. Использовать feature branch workflow

Для каждой задачи необходимо создавать отдельную ветку, что также называется [feature
branch workflow](https://docs.gitlab.com/ee/gitlab-basics/feature_branch_workflow.html)

Например, для [issue 35](https://gitlab.com/Zaynulla/python_for_bmstu_students/-/issues/35)
соответствующую ветку с именем feature/35 можно создать следующей командой:

```bash
git checkout -b feature/35 main  # создаём ветку
```

Команда не только создаёт ветку feature/35 из последнего коммита ветки main, но и
сразу переключает репозиторий в отслеживание новой ветки feature/35. Добавив в конце
аргумент main мы явным образом указываем из какой ветки необходимо сделать ветку
feature/35.

В задании с добавлением своего ФИО изменения необходимо проводить в уже существующей
ветке "print_students". Если работаете с gitflic, то изменения необходимо проводить в
ветке "gitflic_print_students". В ветках настроена защита: на сервер gitlab
заблокирована возможность вносить изменения в ветку gitflic_print_students, а на сервере
gitflic, соответственно, наоборот, заблокирована ветка print_students. Такое усложнение
внедрено временно, т.к. у некоторых студентов не было возможности завести аккаунт в
GitLab, но с сервером Gitflic автор курса пока мало знаком. Если не вводить ограничения
на ветки, то при попытке объединить истории из двух репозиториев возникнут конфликты.

После добавления коммитов опубликовать ветку feature/35 с её коммитами можно командой:

```bash
git push origin feature/35
```

При необходимости внесения изменений, сделать новые коммиты и опубликовать их той же
командой.

Когда задание выполнено, необходимо создать запрос на слияние (merge request) из своей
ветки.

Такая организация работы позволяет не смешивать работу по разным задачам и
автоматическая система проверки домашних заданий ориентирована именно на этот подход в
работе.

## 2. В merge request добавлять соответствующий комментарий

В
[комментарии](https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically)
на запрос слияния (merge request), указать

```text
Closes #35
где вместо 35 поставить номер своего issue
```

Так после подтверждения merge request (запрос на вливание) код окажется в основной
ветке, а issue (задача) будет закрыт автоматически. Выполнение ДЗ учитывается именно по
признаку того, что issue находится в состоянии closed.

## 3. Соблюдать стандартны качества кода

1. В функциях должны быть указаны типы аргументов и возвращаемых значений. Т.е. вместо

    ```python
    def my_func(a, b):
        return a + b
    ```

    Должно быть, например (если передаём вещественные значения):

    ```python
    def my_func(a: float, b: float) -> float:
        return a + b
    ```

1. У функций должны быть добавлены doc-string, для этого удобно использовать расширение
 VSCode
[autodocstring](https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring),
которое делает большую часть работы. В этом проекте данное расширение добавлено в набор по
умолчанию. См. гиф анимацию по работе расширения:
![autodocstring](https://github.com/NilsJPWerner/autoDocstring/raw/HEAD/images/demo.gif)

1. Строки комментариев должны укладываться в длину строки 88 символов (первая вертикальная
   линия). Удобно использовать добавленное в умолчания для проекта расширение
   [rewrap](https://marketplace.visualstudio.com/items?itemName=stkb.rewrap)
   Т.е. вместо:

    ```python
    def my_func(a: float, b: float) -> float:
        """Вычисляет много всего. Делает это замечательно, великолепно. Только документация большая, коротко не описать без потери смысла."""
    ```

    должно быть:

    ```python
    def my_func(a: float, b: float) -> float:
        """Вычисляет много всего. Делает это замечательно, великолепно.
        Только документация большая, коротко не описать без потери смысла.
        """
    ```

1. Код должен быть отформатирован с помощью
[Black](https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter) и
удалены сортированы импорты с помощью
[Ruff](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff). В VSCode
выполняется автоматически при сохранении файла Python. Если форматирование не происходит
автоматически, то см. инструкцию по установке расширений на
[Stepik](https://stepik.org/lesson/1099950/step/7?unit=1110938).

## В репозитории (только Gitlab) настроены проверки

Многие из указанных выше требований реализованы в виде автоматических проверок на
стороне сервера Gitlab. После отправки коммита можно посмотреть свой коммит в
[списке](https://gitlab.com/Zaynulla/python_for_bmstu_students/-/commits/print_students?ref_type=heads).
Необходимо выбрать соответствующую ветку, по ссылке открывается ветка print_students.
Если делали fork, то надо найти аналогичный раздел в своём репозитории. ![Можно кликнуть
на красный крестик](images/gitlab_ci_cd_status.png)

Если видим красный крестик, то на него можно кликнуть и посмотреть где возникла ошибка.
